home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 (Alt) / MACD 5.bin / workbench / monitory / icontrace / it.doc < prev    next >
Encoding:
Text File  |  1994-01-23  |  18.7 KB  |  706 lines
  1.  
  2.  
  3.                        IconTrace v2.02 User's Manual                 1
  4.  
  5.  
  6.                               IconTrace v2.02
  7.  
  8.                         Copyright © 1993 Peter Stuer
  9.                             All rights reserved
  10.  
  11.                       Release date December 14, 1993
  12.  
  13.                                  FREEWARE
  14.  
  15.                                 User Manual
  16.  
  17.  
  18.      COPYRIGHT NOTICE 
  19.  
  20.      IconTrace software and documentation are Copyright © 1993 by
  21.      Peter Stuer.  All rights reserved.  
  22.  
  23.  
  24.      DISCLAIMER 
  25.  
  26.      IconTrace has proven to be stable in everyday use.  The author
  27.      is not responsible for any loss of data, damages to software or
  28.      hardware that may result directly or indirectly from the use of
  29.      this program.  The author reserves the right to make changes to
  30.      the software or documentation without notice.  
  31.  
  32.  
  33.      PREFACE 
  34.  
  35.      This program is freeware, this means that you can copy it freely
  36.      as long as you don't ask any more money for it than a nominal
  37.      fee for copying.  If you want to distribute this program you
  38.      should keep this document with it.  This program cannot be used
  39.      for commercial purposes without written permission from the
  40.      author.  
  41.  
  42.      None of the files of the IconTrace package may be modified or
  43.      left out without permission of the author. Crunching or achiving
  44.      is allowed only if none of the IconTrace files get modified by
  45.      it.  
  46.  
  47.      Special permission is hereby granted to include IconTrace in
  48.      Public-Domain collections such as Fred Fish's Amiga Library.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.      
  65.  
  66.  
  67.                        IconTrace v2.02 User's Manual                 2
  68.  
  69.  
  70.      Chapter 1 Introduction      
  71.  
  72.      1.1 What is IconTrace ?    
  73.  
  74.          IconTrace is a program that allows you to monitor what the
  75.      icon library is doing when you start a program using the
  76.      Workbench.  It's main use lies in discovering undocumented
  77.      ToolTypes and debugging your existing ToolTypes by watching if
  78.      the program finds them correctly. You are also shown what icons
  79.      your programs look for.  
  80.  
  81.  
  82.      1.2 Features of IconTrace     
  83.  
  84.          Currently the following functions can be monitored: 
  85.  
  86.              FindToolType            GetIcon 
  87.              GetDiskObject           MatchToolValue 
  88.              GetDiskObjectNew        PutDiskObject 
  89.              GetDefDiskObject        PutDefDiskObject 
  90.                                      PutIcon 
  91.  
  92.      You can specify which functions IconTrace should monitor.  
  93.  
  94.      IconTrace saves the trace information it gathers as session
  95.      history. It provides a scrollbar which enables you to scroll
  96.      through the session history.  
  97.  
  98.      IconTrace is also a commodity. You can specify a hotkey to show
  99.      or hide the output window.  
  100.  
  101.      IconTrace can open on any public screen.  
  102.  
  103.  
  104.      1.3 System requirements      
  105.  
  106.          IconTrace should run on any Amiga system with at least 512K
  107.      RAM and one disk-drive. IconTrace requires KickStart v2.04 or
  108.      higher to run. Special care has been taken in the program design
  109.      to make the program work with 68020, 68030 and 68040 processors
  110.      without sacrificing 68000 compatibility.  
  111.  
  112.      IconTrace also requires the ReqTools.library v38 or higher.
  113.      ReqTools is copyright © 1992, 1993 by Nico François.  
  114.  
  115.      IconTrace is KickStart 3.0 compatible and aware. It will show
  116.      you some of the new features available with this version of the
  117.      operating system.  
  118.  
  119.      Should you have any trouble running IconTrace on your machine,
  120.      please write to me with the full specifications of your machine,
  121.      that is KickStart version, model, expansion boards etc...  
  122.  
  123.  
  124.      1.4 About the author and the program  
  125.  
  126.  
  127.  
  128.      
  129.  
  130.  
  131.                        IconTrace v2.02 User's Manual                 3
  132.  
  133.  
  134.          IconTrace has been created using the Macro68 Assembler and
  135.      CygnusEd Professional 3 on an Amiga A3000 25/100 with 10MB
  136.      memory.  The IconTrace documentation was formatted with PRoff.  
  137.  
  138.      If you have suggestions or remarks about this program, or if you
  139.      find any bugs, please let me know.  
  140.  
  141.      When sending in bug reports, please state exactly under what
  142.      circumstances the bug occurred, what equipment was used and what
  143.      happened. If possible also try to give me enough information to
  144.      reproduce the bug. It is very difficult to find bugs when you
  145.      don't know exactly what happened.  
  146.  
  147.      Write to the following address: 
  148.  
  149.              Fido     :  2:292/603.7 (Peter Stuer)
  150.              AmigaNet : 39:120/102.7 (Peter Stuer)
  151.              NLA Net  : 14:200/101.7 (Peter Stuer)
  152.  
  153.              UUCP     : Peter.Stuer@p7.f603.n292.z2.FidoNet.Org
  154.  
  155.              SnailMail: Peter Stuer
  156.                         Beatrijslaan 2 bus 13
  157.                         B-2050 Antwerpen L.O.
  158.                         Belgium - Europe
  159.  
  160.      I will also try to put the latest available version of IconTrace
  161.      on the following BBS (this may change without further notice): 
  162.  
  163.              Great Balls Of Fire BBS 
  164.              ReqTools Support BBS 
  165.              Herman Stevens 
  166.              Lubbeek 
  167.              ADS Distribution HUB 
  168.              ABC Host Belgium 
  169.              AFN Host Belgium 
  170.              Tel. +32-(0)16-64.09.12 
  171.              ZyXEL U1496+ 16800 BPS (N.8.1) v32bis v42bis 
  172.              24-24 h.  
  173.              Fido Node  2:292/603 
  174.              NLA Node  14:200/101.0 
  175.              AmyNet    39:120/102.0 
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.      
  193.  
  194.  
  195.                        IconTrace v2.02 User's Manual                 4
  196.  
  197.  
  198.      Chapter 2 Using IconTrace     
  199.  
  200.          You can be start IconTrace from the CLI/Shell or the
  201.      Workbench.  IconTrace will always check to make sure it is not
  202.      already running. If so, the copy of IT that is already running
  203.      will be notified and its window will open or come to the front.
  204.      The second copy will exit quietly.  
  205.  
  206.  
  207.      2.1 Starting IconTrace from the Shell   
  208.  
  209.          To start IconTrace from the Shell simply type: 
  210.  
  211.              1> IconTrace 
  212.  
  213.      followed by a return. If you want to continue using the Shell
  214.      while IconTrace is running, you need to prepend the Run command
  215.      before IconTrace as follows: 
  216.  
  217.              1> run IconTrace 
  218.  
  219.      If IconTrace is succesful in initializing itself, you see the
  220.      IconTrace window and will start monitoring the icon.library. If
  221.      no window is displayed, consult Appendix A (Troubleshooting) for
  222.      more assistance.  
  223.  
  224.  
  225.      2.2 Shell Startup Options     
  226.  
  227.          IconTrace can be started with various options. If you run
  228.      IconTrace with a questionmark (?) as argument you'll get the
  229.      argument template.  
  230.  
  231.  
  232.      HISTORY 
  233.  
  234.        This option tells IconTrace how many lines of history it
  235.        should keep. Use 0 to disable the history feature. The default
  236.        number of history lines is 256.  
  237.  
  238.      OUTPUT 
  239.  
  240.        With this option you can direct the trace information to some
  241.        other AmigaDOS device of file in addition or in place of the
  242.        information being displayed in the window.  
  243.  
  244.        If you have a debugging terminal attached to the serial port
  245.        you could use 'IconTrace OUTPUT=AUX:' to have all trace
  246.        information appear at the terminal.  
  247.  
  248.        A special symbol is DEBUG. 'OUTPUT=DEBUG' will output all
  249.        trace information to the serial port at 9600 baud.  
  250.  
  251.      LEFT 
  252.  
  253.        This option specifies the left position of the IconTrace
  254.  
  255.  
  256.      
  257.  
  258.  
  259.                        IconTrace v2.02 User's Manual                 5
  260.  
  261.  
  262.        output window in pixels. By default, the leftedge will be zero
  263.        (0).  
  264.  
  265.      TOP 
  266.  
  267.        This option specifies the top position of the IconTrace output
  268.        window in pixels. By default, IconTrace will open its window 1
  269.        pixel under the screen title bar.  
  270.  
  271.      WIDTH 
  272.  
  273.        This option specifies the width of the IconTrace output window
  274.        in pixels. By default, IconTrace will open a window that is as
  275.        wide as the visible width of the public screen it is appearing
  276.        on.  
  277.  
  278.      HEIGHT 
  279.  
  280.        This option specifies the height of the IconTrace output
  281.        window in screen lines. By default, IconTrace will open a
  282.        window that is as high as the visible height of the public
  283.        screen it is appearing on, without overlapping the title bar.  
  284.  
  285.      SCREEN 
  286.  
  287.        If you do not use this option, IconTrace will open on the
  288.        default public screen which is most of the times the Workbench
  289.        screen.  IconTrace will try to open on the public screen whose
  290.        name is specified after this argument.  
  291.  
  292.      TRACE/DONTTRACE 
  293.  
  294.        By specifying a trace mask using the TRACE parameter you can
  295.        determine which icon.library functions IconTrace will actually
  296.        trace. The trace mask consists of a string of characters. The
  297.        function corresponding to the character will be traced. Use
  298.        the following characters (case sensitive): 
  299.  
  300.              A: GetIcon              F: PutDiskObject 
  301.              B: GetDiskObject        G: PutDefDiskObject 
  302.              C: GetDefDiskObject     H: FindToolType 
  303.              D: GetDefDiskObjectNew  I: MatchToolValue 
  304.              E: PutIcon 
  305.  
  306.        For example, TRACE=HI will only trace the icon.library
  307.        FindToolType() and MatchToolValue(). By default, IconTrace
  308.        monitors all icon.library functions it knows about.  
  309.  
  310.        Specifying a trace mask for DONTTRACE will make IconTrace
  311.        ignore the functions that you specify here. For example,
  312.        DONTTRACE=a will cause the GetIcon() calls not to be shown.  
  313.  
  314.        The DONTTRACE trace mask always takes precedence over the
  315.        TRACE trace mask.  
  316.  
  317.      CX_PRIORITY 
  318.  
  319.  
  320.      
  321.  
  322.  
  323.                        IconTrace v2.02 User's Manual                 6
  324.  
  325.  
  326.  
  327.        This option allows you to specify priority relative to the
  328.        other Commodities programs. Default priority is 0.  
  329.  
  330.      CX_POPKEY 
  331.  
  332.        This option allows you to change the default hot key for
  333.        IconTrace.  The default hot key is 'ralt i' (right Alt key
  334.        pressed with 'i').  
  335.  
  336.      CX_POPUP 
  337.  
  338.        If you do not want IconTrace to open its window, you can
  339.        specify the CX_POPUP switch like this: DT CX_POPUP=NO. By
  340.        default, the IconTrace window will open.  
  341.  
  342.      CX_ACTIVE 
  343.  
  344.        By specifying CX_ACTIVE=NO, IconTrace start without its
  345.        tracing code enabled. By default, tracing starts immediately.  
  346.  
  347.  
  348.      2.3 Starting IconTrace from the Workbench   
  349.  
  350.          To start IconTrace from the Workbench, simply double-click
  351.      on the IconTrace icon to start the program or use the 'Execute
  352.      Command' item from the 'Workbench' menu.  
  353.  
  354.  
  355.      2.4 Workbench Startup Options     
  356.  
  357.          You can specify the same options as explained in the
  358.      paragraph "Shell Startup Options" by adding tooltypes to the
  359.      IconTrace icon.  
  360.  
  361.  
  362.                                    NOTE
  363.  
  364.           If you use the CX_POPUP and/or the CX_ACTIVE tooltype
  365.           you must specify them with '=YES' appended to them.
  366.           For example, 'CX_POPUP=YES'. Not using them defaults
  367.           to CX_POPUP=YES and CX_ACTIVE=YES.  
  368.  
  369.  
  370.      To change the task priority of IconTrace you can add the TOOLPRI
  371.      tooltype to the IconTrace icon. For example, adding TOOLPRI=5 will
  372.      start running IconTrace with task priority 5.
  373.  
  374.  
  375.      2.5 Stopping IconTrace     
  376.  
  377.          You can stop IconTrace at any time by sending it a break signal. If
  378.      you started IconTrace from the Shell, you can do this by pressing
  379.      Ctrl-C.
  380.  
  381.      Since IconTrace is a commodity you can use the Exchange utility to
  382.  
  383.  
  384.      
  385.  
  386.  
  387.                        IconTrace v2.02 User's Manual                 7
  388.  
  389.  
  390.      control it.
  391.  
  392.        'Show Interface' will open the IconTrace output window
  393.  
  394.        'Hide Interface' will close the IconTrace output window
  395.  
  396.        The 'Active/Inactive' cycle gadget will toggle IconTrace's
  397.        activation status. When IconTrace is active it will update it's
  398.        internal history even when the output window is closed; when it is
  399.        inactive, no tracing will occur.
  400.  
  401.        'Remove' will tell IconTrace to quit.
  402.  
  403.  
  404.                                    NOTE
  405.  
  406.           IconTrace will try to quit immediately. If any of the
  407.           patches are still in use, it will wait until no
  408.           program uses the IconTrace patches anymore.  
  409.  
  410.  
  411.  
  412.  
  413.      2.6 The Project menu    
  414.  
  415.          The Project menu gives you some control over IconTrace's behaviour
  416.      while it is running.
  417.  
  418.      2.6.1 The Active menu item   
  419.  
  420.        IconTrace is 'active' when it is allowed to monitor icon.library
  421.        calls. When this menu item is checked, IconTrace is active.
  422.  
  423.      2.6.2 The Clear menu item   
  424.  
  425.        Clears the session history and the window.
  426.  
  427.      2.6.3 The Hide menu item   
  428.  
  429.        Does the same as the Hide gadget of the Exchange program. IconTrace
  430.        stays in memory and, depending on its activation status, continues
  431.        to trace the icon.library.
  432.  
  433.      2.6.4 The Quit menu item   
  434.  
  435.        This causes IconTrace to try to quit. See also 'Stopping IconTrace'.
  436.  
  437.  
  438.      2.7 About the trace output   
  439.  
  440.          The information shown depends on which function is being traced
  441.      but all messages have 3 components in common:
  442.  
  443.              Process Name    The name of the process calling the
  444.                              icon.library function.
  445.  
  446.  
  447.  
  448.      
  449.  
  450.  
  451.                        IconTrace v2.02 User's Manual                 8
  452.  
  453.  
  454.              Trace Info      Verbose information about the function
  455.                              being executed.
  456.  
  457.              Result          Whether the call was succesfull or not
  458.                              (if applicable)
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.      
  513.  
  514.  
  515.                        IconTrace v2.02 User's Manual                 9
  516.  
  517.  
  518.      :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  519.      ::::::::::::::::::::::: IconTrace HISTORY :::::::::::::::::::::::
  520.      :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  521.  
  522.      ::: Version 2.02 ::: December 14, 1993 ::::::::::::::::::::::::::
  523.  
  524.      - BUG FIX: Fixed a small bug that caused high-ASCII characters
  525.        in filenames to disappear. Thanks to Stefan Ottosson for
  526.        reporting this.
  527.  
  528.      - BUG FIX: The session history was not redrawn if there were less
  529.        lines in the session history than could be displayed. Thanks
  530.        to David Nouls & Bart van Assche for reporting this.
  531.  
  532.      ::: Version 2.01 ::: December 6, 1993 :::::::::::::::::::::::::::
  533.  
  534.      - NEW: LEFT and TOP options let you specify the left and top
  535.        position of the IconTrace window. Thanks to Preben Nielsen for
  536.        suggesting this.
  537.  
  538.      - NEW: IconTrace remembers the position and dimensions of its
  539.        window when it shows it window again after a 'Hide'.
  540.  
  541.      - NEW: You can use the following keys to control the position of
  542.        the session history:
  543.              Cursor Up/Cursor Down           1 line up/down
  544.              Shift Cursor Up/Cursor Down     1 page up/down
  545.              Control Cursor Up/Cursor Down   top/bottom
  546.        Thanks to Magnus Holmgren for suggesting this.
  547.  
  548.      - NEW: To avoid using a ridiculously long TRACEMASK parameter
  549.        if you DON'T want to see the trace results of a function, I
  550.        replaced the TRACEMASK parameter with the TRACE and DONTTRACE
  551.        parameter. For more information, see the documentation.
  552.  
  553.      - NEW: Brought the manual up to date.
  554.  
  555.      - BUG FIX: Due to register leaking IconTrace would exit when it
  556.        reopened its window after another copy of IconTrace woke the
  557.        original up. Thanks to Rafael D'Halleweyn for reporting this.
  558.  
  559.      - BUG FIX: IconTrace ignored the CXPRIORITY argument. Thanks to
  560.        Rafael D'Halleweyn for reporting this.
  561.  
  562.      - BUG FIX: The broker name of IconTrace did not fit completely in
  563.        the provided space by Exchange. Thanks to Rafael D'Halleweyn
  564.        for reporting this.
  565.  
  566.      - BUG FIX: Fixed a bug that could cause a lock-up of the console
  567.        device during a refresh of the history. Thanks to Bart van
  568.        Assche for helping me to track it down.
  569.  
  570.      ::: Version 2.00 ::: November 15, 1993 ::::::::::::::::::::::::::
  571.  
  572.      - Complete rewrite.
  573.  
  574.  
  575.  
  576.      
  577.  
  578.  
  579.                        IconTrace v2.02 User's Manual                10
  580.  
  581.  
  582.      - NEW: Removed the annoying delay when quitting IconTrace. Thanks
  583.        to Rafael D'Halleweyn for the suggestion.
  584.  
  585.      - NEW: Added up/down gadgets to scroll up/down line by line.
  586.  
  587.      - NEW: Added Clear menu item to clear the history buffer while
  588.        IconTrace is running.
  589.  
  590.      - NEW: Added an Active menu item to make activating and
  591.        deactivating IconTrace on the fly easier.
  592.  
  593.      - NEW: Added trace code for undocumented functions GetIcon() and
  594.        PutIcon(). Apparently, the Workbench uses these calls to get
  595.        its icons when opening Workbench windows.
  596.  
  597.        NOTE: If you want to know why it takes so extremely long for the
  598.        Workbench to show a disk/drawer contents in using View By Name
  599.        mode, start IconTrace and be amazed!
  600.  
  601.      - IMPROVED: Optimized some of the core routines.
  602.  
  603.      ::: Version 1.02 ::: June 26, 1993 ::::::::::::::::::::::::::::::
  604.  
  605.      - BUG: The patch of the GetDiskObjectNew used the wrong trace
  606.        code.
  607.  
  608.      - NEW: Made error reporting and failure handling more verbose.
  609.  
  610.      - NEW: Improved and optimized code.
  611.  
  612.      ::: Version 1.01 ::: June 24, 1993 ::::::::::::::::::::::::::::::
  613.  
  614.      - BUG: FindToolType trace code gave wrong results, sorry...
  615.  
  616.      ::: Version 1.00 ::: June 23, 1993 ::::::::::::::::::::::::::::::
  617.  
  618.      - First release
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.      
  641.  
  642.  
  643.      
  644.  
  645.  
  646.                              Table Of Contents
  647.  
  648.                               IconTrace v2.02
  649.  
  650.      Chapter 1 Introduction     ................................    2
  651.         1.1 What is IconTrace ?   ..............................    2
  652.         1.2 Features of IconTrace    ...........................    2
  653.         1.3 System requirements     ............................    2
  654.         1.4 About the author and the program ...................    2
  655.      Chapter 2 Using IconTrace    ..............................    4
  656.         2.1 Starting IconTrace from the Shell  .................    4
  657.         2.2 Shell Startup Options    ...........................    4
  658.         2.3 Starting IconTrace from the Workbench  .............    6
  659.         2.4 Workbench Startup Options    .......................    6
  660.         2.5 Stopping IconTrace     .............................    6
  661.         2.6 The Project menu    ................................    7
  662.            2.6.1 The Active menu item   ........................    7
  663.            2.6.2 The Clear menu item   .........................    7
  664.            2.6.3 The Hide menu item   ..........................    7
  665.            2.6.4 The Quit menu item   ..........................    7
  666.         2.7 About the trace output   ...........................    7
  667.  
  668.      Copyright © 1993 IconTrace v2.02 written by Peter Stuer
  669.  
  670.                   _
  671.                _ //
  672.      Thanks to \X/ Amiga for being the best computer ever !
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.      
  705.  
  706.